/* EntityMapper.java
 *
 * Copyright 2006, Tim Dwelle.
 *
 * Licensed under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in
 * compliance with the License.  You may obtain a copy of
 * the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in
 * writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 * CONDITIONS OF ANY KIND, either express or implied.  See
 * the License for the specific language governing
 * permissions and limitations under the License.
 *
 */

package dowry;

import java.util.*;

/**
 * EntityMapper handles the mapping of some source of entity
 * information (eg Hibernate configuration) into a mapping
 * format suitable for Dowry.
 *
 */
public interface EntityMapper
{
    /**
     * Augments the entity mapping based on the specified
     * attribute value.  This will override any existing
     * value for this attribute.
     *
     * @param entity     the string name of the entity
     *
     * @param property   the string name of the property
     *
     * @param attribute  the string name of the attribute
     *
     * @param value      the attribute value to be included
     *
     */
    public void addAttribute(String entity,
                             String property,
                             String attribute,
                             Object value);

    /**
     * Returns the classes for the mapped entities.
     *
     * @return  a set of class objects representing the
     *          mapped entities
     *
     */
    public Set getClasses();

    /**
     * Returns a mapping of Dowry entities.  The format
     * of this map is:
     *
     * <pre>
     * Map&lt;String entity,
     *     Map&lt;String property,
     *         Map&lt;String attribute, Object value&gt;&gt;&gt;
     * </pre>
     *
     * @return  a map representing the Dowry entities
     *
     */
    public Map getEntityMapping();

    /**
     * Returns the string names for the mapped entities.
     *
     * @return  a set of the the string names of the mapped
     *          entities
     *
     */
    public Set getNames();

    /**
     * Returns a set of all the string Dowry types
     * referenced in this mapping.  This includes both the
     * types of all mapped properties, as well as the types
     * of the entities themselves.
     *
     * @return a set of string names of the Dowry types
     *         represented in the mapping
     *
     */
    public Set getTypes();
}